# Library description
# This Text will be sent to AI's to help them follow instructions.,
--- BLENDER PYTHON LIBRARY DOCUMENTATION ---

You have access to a Python library for Blender. Use the following functions to write scripts.
The library is pre-loaded. Do not use `bpy.ops` directly; use these functions instead.

## USER LIBRARY (High-Level Functions)

### Primitive Creation (With Color)
# Creates a Cube mesh object with an optional color.
# Params: name (str), location (tuple), size (float), color (tuple, optional).
# Returns: bpy.types.Object
Create_Cube(name="Cube", location=(0, 0, 0), size=2.0, color=None)
# Example: new_cube = Create_Cube("RedBlock", color=(1, 0, 0))

# Creates a Plane mesh object with an optional color.
# Params: name (str), location (tuple), size (float), color (tuple, optional).
# Returns: bpy.types.Object
Create_Plane(name="Plane", location=(0, 0, 0), size=2.0, color=None)
# Example: floor = Create_Plane("Floor", size=20, color=(0.1, 0.1, 0.1))

# Creates a UV Sphere mesh object with an optional color.
# Params: name (str), location (tuple), radius (float), segments (int), rings (int), color (tuple, optional).
# Returns: bpy.types.Object
Create_Sphere(name="Sphere", location=(0, 0, 0), radius=1.0, segments=32, rings=16, color=None)
# Example: ball = Create_Sphere("Ball", radius=0.5, color=(0, 0.8, 0))

# Creates an Ico Sphere (geodesic) mesh object with an optional color.
# Params: name (str), location (tuple), radius (float), subdivisions (int), color (tuple, optional).
# Returns: bpy.types.Object
Create_Ico_Sphere(name="IcoSphere", location=(0, 0, 0), radius=1.0, subdivisions=2, color=None)
# Example: golf_ball = Create_Ico_Sphere("GolfBall", subdivisions=4, color=(0.9, 0.9, 0.9))

# Creates a Cylinder mesh object with an optional color.
# Params: name (str), location (tuple), radius (float), height (float), vertices (int), color (tuple, optional).
# Returns: bpy.types.Object
Create_Cylinder(name="Cylinder", location=(0, 0, 0), radius=1.0, height=2.0, vertices=32, color=None)
# Example: pipe = Create_Cylinder("Pipe", height=10, color=(0.5, 0.5, 0.5))

# Creates a Cone mesh object with an optional color.
# Params: name (str), location (tuple), radius (float), height (float), vertices (int), color (tuple, optional).
# Returns: bpy.types.Object
Create_Cone(name="Cone", location=(0, 0, 0), radius=1.0, height=2.0, vertices=32, color=None)
# Example: traffic_cone = Create_Cone("WarningCone", color=(1, 0.3, 0))

# Creates a Torus (donut) mesh object with an optional color.
# Params: name (str), location (tuple), major_radius (float), minor_radius (float), color (tuple, optional).
# Returns: bpy.types.Object
Create_Torus(name="Torus", location=(0, 0, 0), major_radius=1.0, minor_radius=0.25, color=None)
# Example: ring = Create_Torus("Ring", minor_radius=0.1, color=(0.9, 0.7, 0.1))

# Creates a new Monkey (Suzanne) mesh object with an optional color.
# Params: name (str), location (tuple), size (float), color (tuple, optional).
# Returns: bpy.types.Object
Create_Monkey(name="Suzanne", location=(0, 0, 0), size=2.0, color=None)
# Example: gold_monkey = Create_Monkey(color=(0.9, 0.7, 0.1))

### Arrangement and Ordering
# Sorts the selection by object size (volume). The largest object becomes active.
# Params: reverse (bool) - If True, sorts largest to smallest.
# Returns: list[bpy.types.Object]
Sort_Selected_By_Size(reverse=False)
# Example: Sort_Selected_By_Size()

# Aligns selected objects to the active object on a specific axis.
# Params: axis (str) - The axis to align on ('X', 'Y', or 'Z').
# Returns: None
Align_Selected_Objects(axis='Z')
# Example: Align_Selected_Objects(axis='Y')

# Stacks selected objects side-by-side along an axis.
# Params: axis (str) - Stacking axis ('X','Y','Z'), gap (float) - Space between objects.
# Returns: None
Stack_Selected_Objects(axis='X', gap=0.0)
# Example: Stack_Selected_Objects(axis='Z', gap=0.5)

# Distributes selected objects evenly between the two outermost objects.
# Params: axis (str) - The distribution axis ('X', 'Y', or 'Z').
# Returns: None
Space_Selected_Objects(axis='X')
# Example: Space_Selected_Objects(axis='X')

### Procedural Building
# Builds a word from procedurally placed plank objects.
# Params: text (str), start_location (tuple), kerning (float), plank_color (tuple, optional).
# Returns: list[bpy.types.Object]
Build_From_Text(text, start_location=(0, 0, 0), kerning=3.5, plank_color=None)
# Example: Build_From_Text("HELLO", plank_color=(0.8, 0.5, 0.2))

# Builds a multi-layered tower of text.
# Params: text (str), num_layers (int), start_location (tuple), color1 (tuple), color2 (tuple).
# Returns: list[bpy.types.Object]
Build_Text_Tower(text, num_layers=5, start_location=(0, 0, 0), color1=(0.8, 0.5, 0.2), color2=(0.6, 0.4, 0.1))
# Example: Build_Text_Tower("STACK", num_layers=10)

## MAIN LIBRARY (Core Functions)

### Object Selection and Management
# Checks if an object with the given name or reference exists.
# Params: ref (str or bpy.types.Object)
# Returns: bool
Exist_Object(ref)
# Example: if Exist_Object("MyCube"): cprint("It exists!")

# Selects a single object.
# Params: oba (str or bpy.types.Object)
# Returns: None
Select_Object(oba)
# Example: Select_Object("Camera")

# Sets a specific object to be the active object.
# Params: oba (str or bpy.types.Object)
# Returns: None
Set_Active_Object(oba)
# Example: Set_Active_Object("Lamp")

# Gets the currently active object.
# Params: None
# Returns: bpy.types.Object or None
Get_Active_Object()
# Example: active_obj = Get_Active_Object()

# Deselects all currently selected objects.
# Params: None
# Returns: None
Deselect_All()
# Example: Deselect_All()

# Deletes all currently selected objects from the scene.
# Params: None
# Returns: None
delete_selected_objects()
# Example: delete_selected_objects()

# Creates a full, independent copy of an object and its data.
# Params: tocopy (str or bpy.types.Object), col (str or bpy.types.Collection, optional).
# Returns: bpy.types.Object
Copy_Object(tocopy, col=None)
# Example: duplicate_cube = Copy_Object("Cube")

# Changes the name of a specified object.
# Params: oba (str or bpy.types.Object), name (str).
# Returns: bool
Rename_Object(oba, name="NewName")
# Example: Rename_Object("Cube", "BuildingBlock")

### Object Transformation
# Gets or sets the location of an object.
# Params: oba (str or bpy.types.Object, optional), loc (list or tuple, optional).
# Returns: mathutils.Vector
Trans_Location(oba=None, loc=None)
# Example: Trans_Location("Cube", [5, 0, 0])

# Gets or sets the Euler rotation of an object in radians.
# Params: oba (str or bpy.types.Object, optional), rot (list or tuple, optional).
# Returns: mathutils.Euler
Trans_Rotation(oba=None, rot=None)
# Example: Trans_Rotation("Cube", [0, 0, 1.5708]) # 90 degrees on Z

# Gets or sets the scale of an object.
# Params: oba (str or bpy.types.Object, optional), scale (list or tuple, optional).
# Returns: mathutils.Vector
Trans_Scale(oba=None, scale=None)
# Example: Trans_Scale("Cube", [2, 1, 1])

# Applies the location, rotation, and scale transforms of an object.
# Params: oba (str or bpy.types.Object, optional).
# Returns: None
Apply_all_Transforms(oba=None)
# Example: Apply_all_Transforms("MyObject")

# Applies the scale transform of an object, setting its scale values to 1.
# Params: oba (str or bpy.types.Object, optional).
# Returns: None
Apply_Scale(oba=None)
# Example: Apply_Scale("MyObject")

### Material and Color
# Creates a new material and optionally assigns it to an object.
# Params: name (str), oba (str or bpy.types.Object, optional).
# Returns: bpy.types.Material
Mat_Create(name, oba=None)
# Example: my_mat = Mat_Create("Red_Mat", "Cube")

# Sets the color of an object by creating and assigning a new material.
# Params: obj_ref (str or bpy.types.Object), color (tuple), name (str, optional).
# Returns: bpy.types.Material
Set_Object_Color(obj_ref, color=(1.0, 1.0, 1.0), name="")
# Example: Set_Object_Color("MySphere", (0, 0, 1))

### Scene and System
# Prints text directly to the Blender Python console window.
# Params: *args (any) - Values to print.
# Returns: None
cprint(*args, **kwargs)
# Example: cprint("Script finished successfully.")

# Forces an update of the active view layer to show recent changes.
# Params: None
# Returns: None
UpdateView()
# Example: UpdateView()

# Gets or sets the current frame number on the timeline.
# Params: val (int, optional) - Frame number to set.
# Returns: int (if getting)
Current_Frame(val=None)
# Example: Current_Frame(50)

# Sets the location of the 3D cursor in world space.
# Params: x (float), y (float), z (float).
# Returns: None
Set_3D_Cursor_Pos(x=0, y=0, z=1)
# Example: Set_3D_Cursor_Pos(1, 2, 3)

